﻿Release notes and performance tips for ATI 3D Rage
BRender Device Driver
Version for BRender 1.4 by Dave Oldcorn and Andy Pomianowski at
Volume 11 Software

Please note that these notes must are not intended to describe the functionality of the hardware and may not cover all of the limitations involved.  The relevant documentation for the hardware must also be consulted for comprehensive and current information.

Capabilities:
Display:
Screen resolutions:	 800x600, 640x480, 512x384, 400x300, 320x240
       (Windows: render to window and to any DirectDraw full-screen mode)
Output buffer:  		RGB 555 15-bit and RGB 565 16 bit output
(Windows: will support one of 15-bit or 16-bit, depending on driver configuration. In almost all cases this will be 15-bit - changing this requires manual editing of system files.  Will not support the non-configured mode even in full-screen.)
3D Accelerator
16-bit Z buffer (only 3D Rage II)
Mixed Z-sort/Z-buffer rendering (with restrictions - see below)
Sub-pixelmap rendering (as transient structures - see below)
Texture formats:	RGB 555, RGB 565, RGBX/RGBA 8888
       8-bit paletted textures (3D Rage II only)
Texture sizes:	Powers of 2 from 1x1 to 1024x1024, textures do not need to be square
Gouraud shading
Gouraud texture lighting including coloured lights
Dithering (locked on)
MIP-mapping
Bilinear interpolation
Perspective correction
Alpha Blending
Fogging (3D Rage II)
3D Rage I vs 3D Rage II:
Those functions that are marked as being specific to 3D Rage II are not guaranteed to be available. Some functions or features will transparently fail in the application: for example, if 8-bit textures are used with a card on which it is not supported, all the 8-bit textured materials will not have texture maps applied, but the application will still run. Other functions or features will cause the application to fail: for example, Z-buffering, which obviously requires a fail value to come back to the application. 

 The 3D Rage I does not support Z-buffering hence the presence of this card can be can be tested for by attempting to allocate a Z-buffer.  Paletted textures and fogging are only supported on the 3D Rage II. 
Limitations Notes:
1. The 3D Rage supports 15-bit and 16-bit colour output at 640x480, 512x384 and 400x300.  It also supports 32-bit textures.  It does NOT support 320x200 in 3D modes.  If 320x200 resolutions are required, these will have to use non-BRender code (or DOSGfx and the software renderers).
2. 8-bit paletted textures are supported. Any number of textures with any number of palettes are supported. Texture palettes are loaded with the pixelmaps as in standard BRender. The palette for each texture is obtained from the map field of the pixelmap structure (see note 12 below). A default palette for 8 bit textures with NULL map fields can be set up by using BrPixelmapPaletteSet.

3. If using BrZb/ZsRenderBegin/BrZb/ZsRenderEnd rather than just BrZb/ZsSceneRender, avoid the use of 2D operations (Pixelmap fill/copy) between the calls.  Behaviour is undefined should this be attempted. This is also applicable to model custom call-backs.

4. As with most device renderers, the video mode can only be changed by shutting down the device driver with BrZb/ZsEnd and freeing up ALL pixelmaps associated with the device.  

5. Applications should be capable of using BOTH Z-sort and Z-buffered renderers. For cards that do not support Z-buffering, a Z-buffer creation call will fail, and the application should revert to using Z-sort.

6. Do not use rectangle fills on Z-buffer pixelmaps.  Only whole pixelmap clears are supported. Any subsurface fill will fill the whole pixelmap.

7. If  a MIP-mapped texture is supplied to the driver, it will always be rendered MIP-mapped whether MIP-mapping in BRender is ON or OFF.

8. Dithering is locked on.  This should not be a problem because it is free in all shading and texturing modes.  This decision was made because most materials will probably not have BR_MATF_DITHER set (if they are to be used for software renderers) and it provides a great increase in output appearance quality. The 3D Rage II does support enabling/disabling of dither.

9. Sub pixel-maps are supported and should work in the same fashion as BRender's software renderers, however they should be used as transient structures since they are not affected by double buffer operations. Therefore if , rendering  into a sub pixel-mapis required, it should be created immediately before the rendering call(s) and freed immediately afterwards. The overhead on this is not significant. This is also very likely to be a limitation of most device renderers.

10. Mixed Rendering. If mixing both Z-sort and Z-buffer rendering is required within an application then the Z-buffer must be allocated using BrPixelmapMatch before the first rendering call (either Zb or Zs). The driver will fail to create the Z-buffer if a rendering call occurs before the attempt to create it. This is a requirement of our card memory management system.

11. Hidden buffer match operations are not supported, so it is impossible to render into textures.

12. (Windows Driver only) Rendering into a window is possible, but may have a few odd side-effects. The front and back buffers must be the same size, or distortion will be seen. Do not attempt to size the window to a value that is not a multiple of 8 pixels.

15.  Unlit texture modes do not modulate the texture colours with the underlying material colour. In lit rendering modes the material colour and the lighting colour will modulate the texture map.

16.   Fogging does not linearly interpolate across non-smooth-shaded materials. So, for example, the BR_MATF_SMOOTH flag must be set for smooth fogging).
Performance notes
1. For good performance on 2M cards, it is HIGHLY recommended that all applications support 512x384 to save on the utilisation of texture memory. Texture memory is particularly important when doing a Z-sort render, because sort-by-material is lost, which could cause in pathological circumstances the card to have to swap before every texture. See also point 2.
2. Effects such as bilinear interpolation are not expensive (about 30% of polygon render time), which can allow for textures of much lower resolution (save that video memory). This may allow much greater performance if lots of texture swapping would otherwise have occurred.

3. Paletted textures with a well chosen palette should give nearly the same output quality as 16/24 bit textures with a big memory usage reduction. This can improve performance significantly by reducing the need to swap textures into the cache. However, in revisions up to the 3D Rage III, paletted textures are not as quick IF they all use different palettes.  See point 7.

4. The 3D Rage handles models with textures well, but is not very accommodating of highly tessellated models. Its performance is mostly dependent on the number of vertices rendered per frame. For optimum performance, reduce the complexity of models and if possible replace them with texture maps. The amount of screen area filled is not particularly significant.

5. Performance of the 3D Rage driver is greatly enhanced by using float based BRender. The performance of the driver is reduced under fixed point BRender because the fixed to floating point conversions uses up lots of  the processor time.

6. It is possible that in some circumstances it might be advantageous to do a 'no sort' render - such as in an instance where the order of drawing the triangles does not matter, or where there are no overlapping polygons (convex models). (One example might be when distant polygon backgrounds are drawn). This can be achieved in this driver by calling the Z-buffer renderer with a NULL pointer for the Z-buffer. This will give some improvements in back end performance, but polygons drawn with this method will, naturally, not be Z buffered. This also works for the software renderers.

7. Paletted textures. This is fairly complex. If you are going to use many paletted textures within your application, then for the best performance it is important that as many of them as possible use the same palette. Each time the palette is changed during rendering some overhead is involved, and this can become highly significant, especially during Z-sort rendering where there is no sort by material. It is not enough to simply quantise each texture to use the same palette, the application must explicitly set the map fields of all pixelmaps using the same palette to point to that palette before registering the pixelmaps. The reason for this is as follows - When Brender loads a paletted pixel map, it also loads the palette for the pixelmap and creates a unique instance of this palette. This means that even if large numbers of pixelmaps are in reality using the same palette data, they each have their own copy of it. This causes the driver to create many texture palette handles when one would, in fact, suffice. By setting the map fields of the pixelmaps to point to the same instance of the palette the driver only creates a single palette handle, saving both space and time when rendering. This performance overhead may well apply on other future video cards.

8. Linear vs. Perspective texture mapping. On current revisions of the ATI card, linear texture mapping is faster than perspective texture mapping, so it is still worthwhile to use linear texture map objects wherever perspective artefacts are not likely to be visible.

Known Bugs/Problems 
Some of these problems may be due to bugs in the BRender driver and some are problems with the hardware libraries supplied by the manufacturer, these are under continuous improvement and upgrades will be available.  Please contact Argonaut or the hardware manufacturer for details.  Please report any new problems to Argonaut as soon as possible.

1. Draw Edges (Wire frame) mode does not always clip correctly.
2. There are some random pixel artefacts on the display in windowed mode.
3. A small text cursor appears on the display.
4. Disabling then re-enabling fog causes all materials to switch to plain white.
5. Un paletted textures do not work in dos driver.
6. The screen is not properly restored on exit.
7. The mouse does not work if you initialise it before loading the BRender driver.

Note: before the commercial release of any program it is the developers responsibility to ensure that the most recent device driver has been obtained from the hardware manufacturers.
